package com.example.util.myAnnotation;

import com.alibaba.csp.sentinel.EntryType;

import java.lang.annotation.*;


/**
 * @Author 刘武贵
 * @Date 2024-03-04 21:34
 * @Description 功能描述：@SentinelResource注解的说明
 */
/**
 * 该注解适用于方法和类型级别，其在运行时保留，并且可以被子类继承。
 * 它没有参数和返回值，因为它主要用于标记作用域，而不是执行特定的功能。
 * 使用这个注解时，需要对它所标记的方法或类型进行额外的处理或检查。
 */
@Target({ElementType.METHOD, ElementType.TYPE})
/**
 * 该注解用于指定其所修饰的注解在运行时可被Java反射机制读取。
 * 这意味着在程序运行期间可以获取到被此注解标注的注释，并对其进行处理。
 *
 * @Retention 注解标明了该注解的生命周期为运行时。
 * @see java.lang.annotation.RetentionPolicy
 */
@Retention(RetentionPolicy.RUNTIME)
/**
 * 一个继承的注解。
 * 该注解没有参数，也没有返回值，用于标记其后的元素（如类或方法）具有继承特性。
 * 当应用到一个类上时，该注解会被其所有的子类继承。
 */
@Inherited
public @interface MySentinelResource {

    /**
     * 资源名称
     *
     * @return 返回属性的值。如果没有指定，默认返回空字符串。
     */
    String value() default "";

    /**
     * entry类型，标记流量的方向，取值IN/OUT，默认是OUT
     * @return EntryType 返回的条目类型，如果没有指定，默认为OUT。
     */
    EntryType entryType() default EntryType.OUT;

    /**
     * 获取资源类型的方法，默认值为0。
     *
     * @return int 返回资源的类型，如果没有指定类型，默认返回0。
     */
    int resourceType() default 0;

    /**
     * 处理BlockException的函数名称,函数要求：
     * 1.必须是 public
     * 2.返回类型 参数与原方法一致
     * 3.默认需和原方法在同一个类中。若希望使用其他类的函数，可配置
     * blockHandlerClass ，并指定blockHandlerClass里面的方法。
     *
     *  @return 返回一个字符串，代表块处理器的结果。默认情况下返回空字符串。
     */
    String blockHandler() default "";

    /**
     * 存放blockHandler的类,对应的处理函数必须static修饰。
     *
     * @return 返回一个类数组，包含所有指定的处理块类。如果未指定任何处理块类，则返回空数组。
     */
    Class<?>[] blockHandlerClass() default {};

    /**
     * 用于在抛出异常的时候提供fallback处理逻辑。fallback函数可以针对所有类型的异常（除了 exceptionsToIgnore 里面排除掉的异常类型）进行处理。函数要求：
     * 1. 返回类型与原方法一致
     * 2. 参数类型需要和原方法相匹配
     * 3. 默认需和原方法在同一个类中。若希望使用其他类的函数，可配置fallbackClass ，并指定fallbackClass里面的方法。
     *
     * @return 返回一个字符串。如果没有显式地设置值，将返回空字符串。
     */
    String fallback() default "";

    /**
     * 存放fallback的类。对应的处理函数必须static修饰。
     *
     * @return 返回一个字符串，作为默认的回退选项。默认返回空字符串。
     */
    String defaultFallback() default "";

    /**
     * 用于通用的 fallback 逻辑。默认fallback函数可以针对所有类型的异常进行处理。若同时配置了 fallback 和 defaultFallback，以fallback为准。函数要求：
     * 1. 返回类型与原方法一致
     * 2. 方法参数列表为空，或者有一个 Throwable 类型的参数。
     * 3. 默认需要和原方法在同一个类中。若希望使用其他类的函数，可配置fallbackClass ，并指定 fallbackClass 里面的方法。
     *
     * @return Class<?>[] - 返回一个类的数组。默认情况下，返回一个空数组。
     */
    Class<?>[] fallbackClass() default {};

    /**
     * 指定排除掉哪些异常。排除的异常不会计入异常统计，也不会进入fallback逻辑，而是原样抛出。
     *
     * @return Class<? extends Throwable>[] 返回一个异常类的数组，这些异常类都是Throwable的子类。
     */
    Class<? extends Throwable>[] exceptionsToTrace() default {Throwable.class};

    /**
     * 需要trace的异常
     *
     * @return 一个表示应忽略的异常类型的数组。默认情况下，不忽略任何异常类型，返回一个空数组。
     */
    Class<? extends Throwable>[] exceptionsToIgnore() default {};
}